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ABOUT THIS CHAPTER 


Warning: This chapter has not been updated to reflect changes and improvements 
that are available on systems using 32-Bit QuickDraw. For further 
information on 32-Bit QuickDraw, please refer to the 32-Bit QuickDraw 
documentation (available on "Phil & Dave's Excellent CD: The Release 
Version). 


The Control Panel has been made extendible: developers can now supply new user 
controls for the Control Panel to display. 


The new Control Panel presents a scrollable list of control devices, or cdevs, 
rather than a single panel. Each cdev is self-contained. When the user selects 
a control device, controls for the previous cdev disappear and most of the 
Control Panel's window is turned over to the newly selected one. 


This chapter describes how to write a cdev that the new Control Panel will 
recognize and allow users to access. It concludes with the code for a very 
simple example cdev. (Several cdevs are standard on the System Disk; they 
contain all of the functions that were in the old Control Panel, and more.) 
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THE CONTROL PANEL 


Rather than presenting a fixed set of controllable items displayed in a single, 
sectioned window, the new Control Panel presents a scrollable list of cdevs in 
the left quarter of the window. Selecting an icon in the list brings up the 
controls for that cdev on the right side of the panel. When the Control Panel 
is opened, it searches the System Folder for cdevs. Since each cdev appears 
with its own icon in the System Folder, users can easily add or throw away items 
as they need. 


Before going into the details of their construction, you should consider the 
most basic fact about cdevs: they are parts of the Control Panel, and should 
perform functions that belong there—primarily the occasional setting and 
resetting of machine or system preferences. Before designing something as a 
cdev, you should think carefully about whether it belongs in the Control Panel. 


You should also think carefully about the user interface. If the default 
settings are well chosen, most users will rarely need to use the Control Panel. 
Because cdevs are not used routinely, designers should make the user interface 
to their cdevs as straightforward as possible. 


Figure 1 shows the new, extendible Control Panel. 
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Figure 1—Extendible Control Panel 
Figure 1—Extendible Control Panel 
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OPERATION 


When the Control Panel is opened it scans the System Folder for resource files 
of type cdev. Upon finding a cdev file it takes the file's icon and name and 
adds it to the list at the left quarter of the Control Panel window. When the 
Control Panel has found all the cdev files, it puts General at the top of the 
list and opens the General cdev. 


The factory-issue Control Panel has six cdevs in the scrollable list. The 
initial cdevs are, in order of appearance: 


¢ General (all Macintoshes) 

« Keyboard (all Macintoshes) 

¢ Monitors (Macintosh II only) 
¢ Mouse (all Macintoshes) 

¢ Sound (Macintosh II only) 
: ( 


Startup device Macintosh SE and II ) 
The General cdev is always first, and comes up selected the first time the user 
opens the Control Panel. 


Each cdev is self-contained, with a standard structure and interface that is 
Supported by the Control Panel. The Control Panel handles actions that are 
common to all cdevs, such as putting up a dialog window and responding to 
window-related events, displaying dialog items and tracking controls. The cdev 
itself simply describes what's in the dialog (except the cdev icon), and 
contains code for controlling whatever that cdev was designed to do. The 
division of labor between Control Panel and the individual cdevs follows. 


The Control Panel will 


* manage the modeless dialog window for the Control Panel as a whole, 
and respond to events for the window, such as dragging or closing it 

* query cdevs initially, to see if they should be displayed on the 
current hardware 

* manage the list of cdev icons, and respond to user actions on the 
list, such as picking which cdev to run 

e track user actions on cdev controls 

e if requested by a cdev, draw rectangles within the cdev portion of 
the window, and blank out (with light gray) any area of the window 
not needed by the current cdev 

¢ if requested by a cdev, display selected error conditions 

¢ draw dialog items belonging to the cdev that's displayed 

* signal the current cdev to do its part in responding to specific events 


The cdev should 


« supply the standard resources that the Control Panel needs to run 
any cdev (described below) 

¢ draw and respond to user items 

¢ be prepared to handle errors, as described later in this chapter 
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e initialize and shut down when signalled by the Control Panel to do so 
¢ do any updating, activating, deactivating that can't be done 
automatically for dialog items 
* respond to user keystrokes and hits on dialog items or controls, 
when signalled by the Control Panel 
¢ perform whatever actions that cdev was designed to do 


When the user clicks a new control device to select it, the Control Panel 
Signals the current cdev to shut down and removes any items in the dialog that 
belong it. For the new cdev, the Control Panel then loads its code, splices its 
dialog items into the dialog's item list and draws them, signals the cdev to 
initialize, and begins signalling the new cdev, as needed, in response to user 
actions. 


Contents of Cdev Files 


The cdev interface to the Control Panel has two parts: a standard set of 
resources that describe the cdev, and are contained in the cdev resource file; 
second, one of those resources is code, which contains a function that must 
respond to a well-defined set of messages that may be passed to the cdev by the 
Control Panel. 


To be adopted by the Control Panel, a cdev file must contain at least these 
seven resources: 


1. 'DITL' (ID = —4064) 
2. ‘mach' (ID = —4064) 
3. ‘nrcet' (ID = —4064) 
4. 'ICN#' (ID = —4064) 
5. 'BNDL' (ID = —4064) 
6. 'FREF' (ID = —4064) 
7. ‘cdev' (ID = —4064) the code resource 
8. 'CURS' (ID = -4064) 


These standard resources, and others that are unique to the cdev, fall in two 
halves of the same resource ID range, —4033 through —4064. IDs that fall in 
the range —4064 through —4049 are reserved for the resources in the Control 
Panel's cdev interface. IDs in the range —4048 through —4033 can be used by 
individual cdevs. Cdevs that encroach on the Control Panel's range risk 
conflicting with future releases of the Control Panel. 


The rest of this subsection describes the standard cdev resources and the 
messages that the cdev can expect from the Control Panel. The sample cdev file 
at the end of this chapter has examples of the seven resources. 


'BNDL', ICN#', and 'FREF' Resources 

The 'BNDL', 'ICN#' and 'FREF' resources enable the cdev to appear both in the 
Finder™ and Control Panel displays. (An owner resource is also needed for the 
cdev to display its correct icon in the Finder. ) 


‘DITL' Resource 
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The 'DITL' is a standard dialog item list, including all of the items in your 
cdev. When a cdev is opened, the Control Panel concatenates the 'DITL' to its 
own. The coordinates of a cdev's dialog items are relative to the entire 
Control Panel window, not just the cdev portion of the window to the right of 
the list. To fall in the cdev section of the window, items must be entirely 
within the rectangle (1, 89, 253, 320). 


Control Panel 


Mouse Tracking 


(Tablet) (house) 
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Very Slow Slow Fast 


Figure 2—-Dialog Items 
Figure 2—-Dialog Items 


‘mach' Resource 


The 'mach' resource is used by the Control Panel to determine the machines on 
which this cdev can run. It contains two word-sized masks: the Softmask is 
compared to the global variable ROM85 to test for toolbox features (such as 
Color Quickdraw); the Hardmask is compared to the low memory global HwCfgFlgs to 
determine which hardware features are available. The cdev will show up if every 
bit that is 0 in the Softmask is 0 in ROM85 and every bit that is 1 in the 
Hardmask is 1 in HwCfgFlgs. If the Softmask is 0 and the Hardmask is $FFFF 
then the Control Panel sends the cdev a macDev call (described below), otherwise 
it does not. Mask examples: 


Softmask Hardmask Action 

0 $FFFF always call cdev with macDev message 
$FFFF $0000 appear on all machines 

$7FFF $0400 appear on machines with ADB 

$3FFF $0000 appear on Macintosh II only 
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The 'mach' resource enables the Control Panel to cache information about each 
cdev. (The user can force a rebuild of the cache by holding down Command-Option 
while opening the Control Panel. ) 


‘nrct' Resource 


The 'nrct' resource is a list of rectangles. The first word of the resource is 
the number of rectangles in the list; the rest of the resource contains the 
rectangle definitions, using eight bytes per rectangle in (top, left, bottom, 
right) order. 


The Control Panel starts out with a light gray background pattern and then uses 
the rectangles to clear white space for the controls and to draw frames around 
them. The 'nrct' resource, along with the 'DITL' resource, defines the look of 
the cdev panel. 


Rectangle coordinates are relative to the entire Control Panel window. To use 
all of the available space in the cdev area, use one rectangle with coordinates 
(-1, 87, 255, 322). (The coordinates differ from those given in 'DITL' by 
exactly two pixels, which is the width of the frame Control Panel draws around 
each rectangle.) To join two panels neatly, overlap their rectangles by one 
pixel on the side where they meet, so that the rectangle frames overlap too. 
For example, the two cdev rectangles in Figure 2 have the coordinates (-1, 87, 
100, 266) and (98, 87, 159, 266). 


If the number or sizes of rectangles you want varies (as in the Macintosh II 
Monitors cdev), the easiest way to manage it is to define rectangles covering 
the maximum area, and paint out those you don't want at run time with the same 
gray pattern Control Panel uses, or frame them yourself. 


‘cdev' Code Resource 

The 'cdev' code resource contains all of your code to handle the other part of 
the cdev interface, the events that are passed to you by Control Panel. The 
very first piece of code in this resource must be the cdev function, as 
described below. 


eeeClick on the X-Ref button, and refer to Technical Note #215, eee 
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CDEV CALL 


The cdev function should be the first piece of code in your ‘'cdev' resource. 
Its calling sequence is as follows: 


FUNCTION cdev(message, Item, numItems, CPanelID: INTEGER; 
VAR theEvent: EventRecord; cdevValue: LONGINT; CPDialog: 
DialogPtr) : LONGINT; 


Field descriptions 


message A message number, from the list defined below, that allows the 
Control Panel to tell the cdev what event has just taken place. 


Item For hitDev messages only: the dialog item number of the item 
that was hit. Since the cdev's DITL is appended to the Control 
Panel's DITL, the number of items preceding the cdev's must be 
subtracted to get a value that is meaningful to the cdev. 
(See the hitDev message, described below. ) 


numitems The number of items in the DITL, belonging to the Control 
Panel, that precede the cdev's dialog items in the item list. 


CPanelID The base resource ID of the Control Panel driver. This 
value is private to the Control Panel. 


theEvent For hit, null, activate, deactivate, and key events: the 
event record for the event that caused the message. See 
the Toolbox Event Manager for details of the EventRecord 
structure. 


cdevValue The value the cdev returned the last time it was called by 
the Control Panel, or a return message from the Control Panel. 
When a cdev is initialized it typically allocates some storage 
for state information or other data it needs to run. Since 
desk accessories in general and the Control Panel in 
particular—and therefore cdevs—cannot have global variables, 
the cdevValue, which is passed to the cdev for every message, 
is often used for storing data. The cdevValue is also used 
by the Control Panel to communicate error handling action to 
the cdev. See "Storage in a Cdev" and "Cdev Error Checking" 
later in this chapter. 


CPDialog The Control Panel DialogPtr. This may be a color dialog on 
Macintoshes that support color windows. 


The function value returned will be one of three kinds. The Control Panel's 
initial call to a cdev will be a macDev call, described below. The cdev 
responds with a function value that tells the Control Panel whether the cdev 
should be displayed or not. In subsequent calls the cdev function result may be 
an error code, or data that needs to be kept until the Control Panel's next 
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call. The function result is generally passed back to the cdev in the cdevValue 
parameter at the next cdev function call. 


The cdev will be called with the current resource file set to the cdev file, the 
current grafPort set to the Control Panel's dialog, and the default volume set 
to the System Folder of the current startup disk. The cdev must preserve all of 
these. Also note that the Control Panel sets the cursor to the cross cursor 
whenever it is above the cdev area of the Control Panel window. Your cdev thus 
has control of the cursor only during the call; if you change it, the Control 
Panel will immediately reset it. 


Your cdev may be reentered, especially if you put up dialog or alert boxes. The 
Dialog Manager calls SystemEvent and SystemTask, which may cause a deactivate 
message to be sent while your cdev is still processing the previous message. 


Messages 


The following cdev message values have been defined: 


CONST 
initDev = 0; {initialization} 
hitDev =" 1 {user clicked dialog item} 
closeDev =D {user selected another cdev or CP closed} 
nulDev = 3; {desk accessory run} 
updateDev = 4; {update event} 
activDev =D: {activate event} 
deActivDev = 6; {deactivate event} 
keyEvtDev = 7; {key-down or auto-key event} 
macDev = 8; {check machine characteristics} 
undoDev = 9; {standard Edit menu undo} 
cutDev =10; {standard Edit menu cut} 
copyDev =11; {standard Edit menu copy} 
pasteDev =12; {standard Edit menu paste} 
clearDev =13; {standard Edit menu clear} 
cursorDev =14; {cursor moved event} 


The messages are described below. 


Before dispatching to handle a specific message, all cdevs should have some 
common defensive behavior, for example ensuring that they have enough memory to 
run. Public-minded cdevs keep a minimum of memory allocated between calls, and 
memory that was free may be consumed by other applications while Control Panel 
is inactive, so it is important to check that there is enough memory available 
on every message. 


As part of their memory check, cdevs that depend on various Toolbox packages 
should ensure that there's still room to load them. Cdevs should also ignore 
any messages (except macDev) received before initialization, or after shutdown 
or an error. 


Your cdev, as part of a desk accessory that may move from one invocation to 
another, cannot use global variables. This in turn means that you cannot set 
user item procedures for drawing user items in the 'DITL', because the procedure 
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pointers will dangle if the code moves. Instead, you must draw your user items 
in response to update messages. Also, you must find Quickdraw globals by means 
of thePort if you need to reference them. 


See the sample cdev for examples. 
The macDev Message 


If the 'mach' resource has a 0 in Softmask and a —1 ($FFFF) in Hardmask, the 
first message a cdev will get is a macDev message. This is an opportunity for 
the cdev to determine whether it can run, and whether it should appear in the 
Control Panel's cdev list. The cdev can do its own check to see which machine 
it is being run on, what hardware is connected, and what is in the slots (if it 
has slots). The cdev must then return a function result of 1 or 0. If a0O is 
returned, the Control Panel will not display the cdev in the icon list. (Note 
that the Control Panel does not interpret this 0 or 1 as an error message as 
described under "Cdev Error Checking". ) 


The macDev call happens only once, and only when Softmask and Hardmask are 0 and 
FFFF. It is always the first call made to the cdev. 


The initDev Message 


InitDev is an initialization message sent to allow the cdev to allocate its 
private storage (if any) and do any initial settings to buttons or controls. 
This message is sent when the user clicks on the cdev's icon. 


Note that the dialog, cdev list, and all of the items in the cdev's 'DITL' 
except user items will already have been drawn when the initDev message is sent. 


If your cdev doesn't need any storage it should return the value that was passed 
to it in cdevValue. 


The activDev Message 


An activDev message is sent to the cdev on every activate event. It allows the 
cdev to reset any items that may have changed while the Control Panel was 
inactive. It also allows the cdev to send things such as "lists activate" 
messages. 


The updateDev Message 


An updateDev message is sent to the cdev on every update event. It allows the 
cdev to perform any updating necessary aside from the standard dialog item 
updating provided by the Dialog Manager. For example, if the cdev resource 
contains a picture of the sound control bar, it will probably be a user item, 
and the picture of the control bar and the volume knob should be redrawn in 
response to update events. 


Note that there is no mechanism for determining what to update, as the update 
region has already been reset. You must redraw all of your user items 
completely. 


The nulDev Message 
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A nulDev message is sent to the cdev on every Control Panel run event. This 
allows the cdev to perform tasks that need to be executed continuously 
(insertion point blinking, for example). 


A cdev cannot assume any particular timing of calls from applications. Don't 
use nulDev to refresh settings; see activDev, above. 


The hitDev Message 


A hitDev message is sent when the user has clicked an enabled dialog item that 
belongs to the cdev. The dialog item number of the item hit is passed in the 
Item parameter. Remember that the Control Panel's items precede yours, so 
you'll want (Item — numItems) to determine which of your items was hit. If the 
Control Panel itself has n items, the first of the cdev's items will be n+1 in 
the combined dialog item list. A cdev should not depend on any hardcoded value 
for numItems, since the number of items in Control Panel's 'DITL' is likely to 
change in the future. 


Factoring in numItems need not mean an increase in your code size, or passing 
and adding numItems everywhere, or foregoing the constants that most developers 
use to identify specific items. You can do it easily, and neatly, as follows: 


1. Subtract numItems from Item right away, and refer to your dialog 
items with constants as usual throughout the cdev. 

2. Write simple envelope routines to enclose Dialog Manager procedures 
that require item number arguments. Add numItems only locally, 
within those routines and for the Dialog Manager calls only. 


This is demonstrated in the sample cdev. 
The keyEvtDev Message 


A keyEvtDev message is sent to the cdev on every keyDown event and autoKey 
event. It allows the cdev to process key events. On return to the Control 
Panel, the key event will be processed by a call to dialogSelect in the Dialog 
Manager. A cdev that does not want the Toolbox Event Manager to do any further 
processing should change the what field of the EventRecord to nullEvent before 
returning to the Control Panel. 


The deActivDev Message 


A deActivDev message is sent to the cdev on every deactivate event. It allows 
the cdev to send deactivate messages to items such as lists. 


The closeDev Message 

A closeDev message is sent to the cdev when either the Control Panel is closed 
or the user selects another cdev. When a cdev receives a closeDev message it 
should dispose of any storage it has allocated, including the handle stored in 
cdevValue, if any. 


The Standard Edit Menu Messages 
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Values 9 through 13 have been defined in order to provide the standard Edit menu 


functions of Undo, Cut, Copy, Paste, and Clear for applications that need to 
implement them. 


eeeClick on the X-Ref button, and refer to Technical Note2 #215 & #25l.e¢ee 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE CONTROL PANEL ¢ 13 of 27 


STORAGE IN A CDEV 


Since normal global storage is not available, the Control Panel, like all desk 
accessories, uses a special mechanism to store values between calls. The 
cdevValue parameter in the cdev call extends this storage mechanism to cdevs. 


If a cdev needs to store information between calls it should create a handle 
during the initDev call, and return it as the cdev function result. The Control 
Panel always returns such handles in the cdevValue parameter at the next call. 


If the cdev is called with a closeDev message, or if it needs to shut down 
because of an error, then this handle and any pointers or handles within the 
storage area should be disposed of before returning to the Control Panel. 
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CDEV ERROR CHECKING 


Because a desk accessory may be called into many strange and wonderful 
Situations, careful attention must be paid to error checking. The two most 
common error conditions are missing resources and lack of memory. Some error 
reporting and recovery facilities have been provided in the Control Panel to 
help with errors encountered in a cdev. 


Because the Control Panel has no direct information about the cdev, the cdev's 
code must be able to detect and recover from error conditions on its own. If 
the recovery cannot be effected the cdev must dispose of any memory it has 
allocated, and exit back to the Control Panel with an error code. 


Following a shutdown, the Control Panel can help report the error condition to 
the user and prevent accidental reentry into the cdev that might result from 
such things as an update event. A cdev can request three different error 
reporting mechanisms from the Control Panel: 


e If a memory error has occured, then, after the cdev has safely shut 
itself down, it may request the Control Panel to issue an out-of-memory 
error message and gray out (paint over with the background pattern) the 
cdev area of the Control Panel window. It will remain grayed until 
another cdev is selected. The Control Panel window itself is not 
closed since other cdevs may still be able to function in the environment. 

e If a resource error is detected, the cdev may request that a 
can't-find-needed-resource error message be issued. 

« The cdev may display its own error message and then call on the 
Control Panel to gray its area. 


The Control Panel uses the cdevValue parameter to send status information to the 
cdev, and a proper cdev uses its function value to send information back to the 
Control Panel. In the absence of errors, the same value passes back and forth: 
the Control Panel puts the last function value it received into cdevValue when 
it calls the cdev; the cdev returns the value it finds there as the function 
value. The cdev may want to keep a handle to its own storage, in which case 
passing it as the function value ensures its availability, since the Control 
Panel will pass it back in cdevValue at the next call. 


Four constants have been defined for this cdev/Control Panel communication: 


CONST 
cdevUnset = 3; {initial value passed in cdevValue} 
cdevGenErr = -1; {generic cdev error} 
cdevMemErr = 0; {insufficient memory for cdev execution} 
cdevResErr = 1; {missing resource needed by cdev} 


After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that 
until an error occurs or the cdev uses its function value as a handle, cdevUnset 
is passed back and forth. If the cdev encounters an error, it should dispose of 
all handles and pointers it has set up, strip the stack back to the same 
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position as a normal exit, and return one of the three error codes as the 


function result. 


Function 
Result 


cdevGenErr 


cdevMemErr 


cdevResErr 


all other values, 
either handles 
or cdevUnset 


The cdev code should check cdevValue at entry. 


Message to 
Control Panel 


The cdev has encountered an 
error from which it cannot 
recover, but do not put up 
an error dialog. 


The cdev has determined that 
there is not enough memory to 
execute; please put up a 
memory error dialog. 


The cdev can't find a needed 


resource; please put up a 
resource error dialog. 


No error conditions. 


The Control Panel will respond as follows: 


Control Panel Action 


Gray out the cdev's area, 
send a 0 in cdevValue in 
succeeding cdev calls 


Gray out cdev's area, put 
up error dialog, send a 0 
in cdevValue in succeeding 
cdev calls. 


Gray out cdev's area, put 
up error dialog, send a 0 
in cdevValue in succeeding 
cdev calls. 


Send the value back in 
cdevValue. 


A 0 means that the Control Panel 


has responded to a cdev error message by shutting down the cdev and displaying 


an error dialog if one was requested. 


The cdev should immediately exit. 


Once the Control Panel has responded to an error message from a cdev it will no 
longer respond to any return values until another cdev is launched. 


The sample cdev code presented next includes error checking. 
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SAMPLE CDEV 


Following is a REZ resource file containing resource definitions for a sample 
cdev. The cdev code resource is provided by the Pascal code that follows. When 
executed, the cdev puts up a control window that has two buttons, and displays 
how many messages it has received, as shown in Figure 3. 


Control Panel 


fi Messages received by Sample: 


Keyboard (@) Show Handled: 2 


a) Hide Ignored: 42 


Monitors 


roy 


Figure 3-—Sample cdey 
Figure 3—Sample cdev 


* File Sample.r 
* Copyright © 1986, 1987 Apple Computer, Inc. All rights reserved. 
* 


* Sample cdev rez file 
1 


#include "Types.r" 
type 'samp' as 'STR ''; 
type 'nrct' { 


integer = $$CountOf (RectArray) ; 
array RectArray { rect; }; 
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ie 


type 'mach' { 
unsigned hex integer; /* Softmask */ 
unsigned hex integer; /* Hardmask */ 


| 


/* The owner resource (related to the BNDL below). See Inside 
Macintosh Volume IV for more information. */ 

resource 'samp' (0, purgeable) { 

"Sample cdev 1.0d2, June 23, 1987" 

pi 


resource 'BNDL' (-4064, purgeable) { 
‘samp', 0, 
{ ‘ICN#', {0, -4064}, 
'FREF', {0, -4064} 
} 


yi 


resource 'ICN#' (-4064, purgeable) { 
{ /* array: 2 elements */ 

JPET Se 

$"FFFF FFFF 8000 0001 8000 0001 8000 0001" 
$"800E 0001 800E 0001 800E 0001 800E 0001" 
$"800E 0000 78FE 3E33 F9OFE 7F33 F9OFE 6333" 
$"E1CE 7F33 E1CE 7F33 E1CE 603F F9OFE 7F1E" 
$"FOFE 7F1E 78FE 3FOQC 8000 0001 8000 0001" 
$"8000 0001 8000 0001 8000 0001 8000 0001" 
$"8000 0001 8000 0001 8000 0001 8000 0001" 
$"FFFF FFFF 0000 0000 0000 0000 0000 0000", 


$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF" 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF" 
$"FFFF FFFE 7FFF FFFF FFFF FFFF FFFF FFFF" 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFE" 
$"FFFF FFFE 7FFF FFFE FFFF FFFF FFFF FFFF" 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF" 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF" 
$"FFFF FFFF 0000 0000 0000 0000 0000 0000" 
} 
1 


resource 'FREF' (-4064, purgeable) { 
‘cdev', 0, wu 


| 


resource 'mach' (-4064, purgeable) { 
OXxFFFF, 
0 

hi 


resource 'nrct' (-4064, purgeable) { 
{ /* array RectArray: 1 elements */ 
{-1, 87, 79, 322} 
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} 
ie 


resource 'DITL' (-4064, purgeable) { 
{ /* array DITLarray: 8 elements */ 


{4, 287, 16, 320}, StaticText {disabled, "1.0d2"}; 
{4, 92, 16, 280}, StaticText {disabled, "Messages } 
{ received by Sample:"}; 
{26, 122, 43, 170}, Control {enabled, -4048}; 
{42, 122, 59, 170}, Control {enabled, -4047}; 
{29, 190, 41, 230}, StaticText {disabled, "Handled:"}; 
{45, 190, 57, 230}, StaticText {disabled, "Ignored:"}; 
{29, 240, 39, 300}, UserItem {disabled}; 
{45, 240, 55, 300}, UserItem {disabled} 
} 
a 
/ *=----=- = = = SS Se eS SS = SS = SS SS SS SS = SS SS SS = = SS SS = = = = = = = == = = = == == 


* Resources that are private to the Sample cdev (IDs for these 

* must fall in the range -4048 to -4033). All those above (-4064 
* to -4049) are standard for every cdev, and specified by Control 
* Panel. */ 


resource 'CNTL' (-4048, purgeable) { 
{26, 122, 43, 170}, 0, visible, 1, 0, radioButProcUseWFont, 0, } 
{ "Show" 

}; 


resource 'CNTL' (-4047, purgeable) { 
{42, 122, 59, 170}, 0, visible, 1, 0, radioButProcUseWFont, 0, } 
{ "Hide" 

i 
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The Pascal source code for the ‘'cdev' code resource: 
{Copyright © 1986, 1987 Apple Computer, Inc. All rights reserved. } 


{Sample: A small cdev code resource for use by Control Panel 3.0. The } 
{ cdev has two radio buttons, labeled "Hide" and "Show", which cause } 

{ four other items to be visible or invisible. The four } 

{ visible/hidden items are the number of messages handled by the cdev, } 
{ the number ignored, and titles for those two counts. Note that } 

{ Sample violates the prime directive for cdevs, i.e. that it do } 

{ something that's really useful in Control Panel...} 


{$D+} {turn debugging symbols on} 
UNIT cdev; 


INTERFACE 


USES 
MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf; 


FUNCTION Sample (message, item, numItems, CPanelID: INTEGER; 
theEvent: EventRecord; cdevValue: LONGINT; 
CPDialog: DialogPtr) : LONGINT; 
IMPLEMENTATION 


CONST 
{ Constants for all of Sample's dialog items } 


iVersion = 1; {cdev's version number is just staticText} 
iTitle = 2; {title for Sample is just staticText} 
iShowCounts = 3; {show the events handled/ignored} 
iHideCounts = 4; {hide the events handled/ignored} 
iTitleHandled = 5} {title for events handled count} 
iTitleIgnored = 6; {title for events ignored count} 
iHandled = 7; {user item for number of events handled} 
iIgnored = 8; {user item for number of events ignored} 
TYPE 

SampleStorage = RECORD 

dlgPtr: DialogPtr; 

dlgitems: INTEGER; 

countShown: BOOLEAN; 

msgHandled: INTEGER; 

msgIgnored: INTEGER; 

END; 
SamplePtr = “SampleStorage; 
SampleHdl = “SamplePtr; 


FUNCTION InitSample (CPDialog: DialogPtr; 

numItems: INTEGER): LONGINT; FORWARD; 
FUNCTION EnoughRoomToRun (VAR cdevValue: LONGINT) : BOOLEAN; FORWARD; 
PROCEDURE CountMessage (ourHandle: SampleHdl; handledIt: BOOLEAN); FORWARD; 
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PROCEDURE HitSample (ourHandle: SampleHdl; item: INTEGER); FORWARD; 
PROCEDURE DrawSampleItem (ourHandle: SampleHdl; item: INTEGER); FORWARD; 
FUNCTION IGetCtlHand (ourHandle: SampleHdl; 

item: INTEGER): ControlHandle; FORWARD; 
PROCEDURE IGetRect (ourHandle: SampleHdl; item: INTEGER; 

VAR itemRect: Rect); FORWARD; 

PROCEDURE IHide (ourHandle: SampleHdl; item: INTEGER); FORWARD; 
PROCEDURE IShow (ourHandle: SampleHdl; item: INTEGER); FORWARD; 
PROCEDURE IInvalidate (ourHandle: SampleHdl; item: INTEGER); FORWARD; 


{Sample: the cdev dispatch function, as documented above. The cdev } 

{ function MUST be the first code in the code resource; Control Panel } 
{ jumps to the first location in the 'cdev' code resource to dispatch } 
{ messages to the cdev. } 


FUNCTION Sample (message, item, numItems, CPanelID: INTEGER; 
theEvent: EventRecord; cdevValue: LONGINT; 
CPDialog: DialogPtr) : LONGINT; 


VAR 
‘Lt INTEGER; 
handledIit: BOOLEAN; 
ourHandle: SampleHdl; 
storageExpected: BOOLEAN; 
BEGIN 


{Do a validity check before trying to handle the message. } 
{ cdevValue is initialized to cdevUnset by Control Panel; zero } 
{ is the new cdevValue after any error return.} 
storageExpected := NOT ((message = initDev) 
OR (message = macDev)); 
IF storageExpected AND ((cdevValue = Q@) 
OR (cdevValue = cdevUnset) ) 
THEN cdevValue := 0 
{Equally important, we must check that there's still enough } 
{ memory available for Sample to run, on every message. Memory 
{ can easily be consumed by other apps, etc, between messages, 
{ and (to be neighborly) we don't keep anything around between 
{ messages except the handle in cdevValue.} 
ELSE IF storageExpected & NOT EnoughRoomToRun (cdevValue) THEN 
BEGIN 
{We're past initialization, and have been hit with a memory } 
{ squeeze. Escape now, averting mayhem. } 


wee 


END 
ELSE 

BEGIN 

handledIt := TRUE; 

ourHandle := SampleHdl (cdevValue) ; 

CASE message OF 

initDev: IF EnoughRoomToRun (cdevValue) THEN 

BEGIN 
cdevValue := InitSample 


(CPDialog, numItems) ; 
ourHandle := SampleHdl 
(cdevValue) ; 
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END; 
closeDev: IF ourHandle <> NIL THEN 
BEGIN 
DisposHandle (Handle 
(ourHandle) ); 


cdevValue := 0; 
ourHandle := NIL; 
END; 
hitDev: HitSample (ourHandle, item - numItems) ; 
updateDev: FOR i := iHandled TO iIgnored DO 
DrawSampleItem (ourHandle, i); 
OTHERWISE handledIt := FALSE; 


END; 

IF ourHandle <> NIL THEN 
CountMessage(ourHandle, handledIt); 
END; 


Sample := cdevValue; 
END; 
{ 

{InitSample: Initialize the cdev} 


FUNCTION InitSample (CPDialog: DialogPtr; numItems: INTEGER): LONGINT; 
VAR 


i: INTEGER; 
ourHandle: SampleHdl; 
BEGIN 


ourHandle := SampleHdl (NewHandle (SIZEOF (SampleStorage) )); 
IF ourHandle <> NIL THEN 


BEGIN 

WITH ourHandle** DO 
BEGIN 
dlgPtr := CPDialog; 
dlgItems := numItems; 
msgHandled := 0; 
msgignored := 0; 
countShown := TRUE; 
END; 


FOR i := iShowCounts TO iHideCounts DO 
SetCtlValue (IGetCtlHand (ourHandle, i), ORD (i = iShowCounts) ); 
END; 
InitSample := ORD4 (ourHandle) ; 
END; 


{EnoughRoomToRun: check that we still have room to run; close up if not } 


FUNCTION EnoughRoomToRun (VAR cdevValue: LONGINT) : BOOLEAN; 


VAR 
error: INTEGER; 
packHand: Handle; 
BEGIN 


{Make sure there is still room for the maximum amount of memory } 
{ needed to process any event, AND for any packages or other } 
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{ resources you need at the same time. If you allocate lots of } 
{ storage, you should account for that also if it hasn't been } 
{ allocated yet. Sample needs the Binary/Decimal conversion } 
{ package to display the event counts. } 
{ In the interest of simplicity, this does NOT take into account } 
{ the fact that PACK 7 may be in ROM; it really should.} 
packHand := GetResource ('PACK', 7); 
IF packHand <> NIL THEN 
BEGIN 
EnoughRoomToRun := TRUE; 
EXIT (EnoughRoomToRun) ; 


END 

ELSE IF ResError = resNotFound 
THEN error := cdevResErr {a needed resource is missing} 
ELSE error := cdevMemErr; {assume memFull otherwise} 


{There's too little memory to load the package. Try to fail } 

{ gracefully, disposing of our storage if it's already been } 

{ allocated, because the error code we return to Control Panel } 

{ will replace cdevValue. } 

IF (cdevValue <> cdevUnset) AND (Handle (cdevValue) <> NIL) THEN 
DisposHandle (Handle (cdevValue) ); 

cdevValue := error; 

EnoughRoomToRun := FALSE; 


END; 
peclrchsta stb tala Cer niche co staat ke ees a oa AE i arin iota Al nna Rhett Ak tat ay at 03 ta ck ft, } 
{CountMessage: count message from Control Panel as handled/ignored} 
PROCEDURE CountMessage (ourHandle: SampleHdl; handledIt: BOOLEAN) ; 
BEGIN 
IF ourHandle <> NIL THEN 
WITH ourHandle** DO 
IF handledIt THEN 
BEGIN 
msgHandled := msgHandled + 1; 
DrawSampleItem (ourHandle, iHandled) ; 
END 
ELSE 
BEGIN 
msgIgnored := msgIgnored + 1; 
DrawSampleItem (ourHandle, ilIgnored) ; 
END 
END; 
Sete Mas Be Megat tana yey Ss eye goceaye: everanehcnace tare oR carat ave, Smatca GPa btn or Se auet cs Roel c9 es os Soe } 


if 
{HitSample: Handle a hit in one of our DITL items} 


PROCEDURE HitSample (ourHandle: SampleHdl; item: INTEGER) ; 
VAR 
i: INTEGER; 
BEGIN 
WITH ourHandle** DO 
IF countShown <> (item = iShowCounts) 
THEN countShown := (item = iShowCounts) 
ELSE EXIT (HitSample) ; 
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FOR i := iShowCounts TO iHideCounts DO 
SetCtlValue (IGetCtlHand (ourHandle, i), ORD (i = item)); 
FOR i := iTitleHandled TO iIgnored DO 
BEGIN 
IF item = iShowCounts 
THEN IShow (ourHandle, i) 
ELSE IHide (ourHandle, i); 
IInvalidate (ourHandle, i); 
END; 


{DrawSampleItem: Draw one of our DITL user items} 


PROCEDURE DrawSampleItem (ourHandle: SampleHdl; item: INTEGER); 
VAR 


itemRect: Rect; 
S: Str255; 
BEGIN 


{Note that Sample draws its user items explicitly, rather than } 
{ installing a pointer to the draw procedure in the dialog item. } 
{ Since the cdev's code may move between messages, the pointer } 
{ would become invalid (Control Panel often calls the dialog } 
{ manager before the cdev, so there's no chance to refresh the } 
{ pointer either) .} 
IGetRect (ourHandle, item, itemRect) ; 
WITH ourHandle** DO 
BEGIN 
SetPort (dlgPtr); 
IF item = iHandled 
THEN NumToString (msgHandled, s) 
ELSE NumToString (msgIgnored, s); 
END; 
WITH itemRect DO 
MoveTo (left, bottom); 
TextMode (srcCopy); 
DrawString (s); 
TextMode (srcOr); 


{Simple routines enclosing the dialog manager functions we need, to} 
{ tack on numItems (so we can refer to our items with constants } 
{ everywhere else). } 


{IGetCtlHand: get control handle for given dialog item} 
{IGetRect: get rectangle for given dialog item} 

{IHide: hide dialog item} 

{IShow: show dialog item} 

{IInvalidate: erase & invalidate dialog item} 


FUNCTION IGetCtlHand (ourHandle: SampleHdl; item: INTEGER): ControlHandle; 
VAR 
itemHand: Handle; 
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itemRect: Rect; 
itemType: INTEGER; 
BEGIN 
WITH ourHandle** DO 
GetDItem (dlgPtr, item + dlgItems, itemType, itemHand, itemRect); 
IGetCtlHand := ControlHandle (itemHand) ; 
END; 


PROCEDURE IGetRect (ourHandle: SampleHdl; item: INTEGER; VAR itemRect: Rect); 
VAR 


itemType: INTEGER; 
itemHand: Handle; 
BEGIN 


WITH ourHandle** DO 
GetDItem (dlgPtr, item + dlgItems, itemType, itemHand, itemRect); 
END; 


PROCEDURE IHide (ourHandle: SampleHdl; item: INTEGER); 
BEGIN 
WITH ourHandle** DO 
HideDItem (dlgPtr, item + dlgItems); 
END; 


PROCEDURE IShow (ourHandle: SampleHdl; item: INTEGER); 
BEGIN 
WITH ourHandle** DO 
ShowDItem (dlgPtr, item + dlgItems); 
END; 


PROCEDURE IInvalidate (ourHandle: SampleHdl; item: INTEGER); 
VAR 
itemRect: Rect; 
BEGIN 
IGetRect (ourHandle, item, itemRect); 
EraseRect (itemRect); 
InvalRect (itemRect); 
END; 


END. 
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SUMMARY OF THE CONTROL PANEL 


Constants 
CONST 


{ messages } 


initDev = 0; {initialization} 

hitDev = 1; {user clicked on dialog item} 
closeDev ="2e {user selected another cdev or CP closed} 
nulDev = 3; {desk accessory run} 

updateDev = 4; {update event} 

activDev = 5; {activate event} 

deActivDev = 6; {deactivate event} 

keyEvtDev = 7; {key down or autokey event} 
macDev = 8; {check machine characteristics} 
undoDev = 9; {standard Edit menu undo} 
cutDev =10; {standard Edit menu cut} 
copyDev =11; {standard Edit menu copy} 
pasteDev =12; {standard Edit menu paste} 
clearDev =13; {standard Edit menu clear} 
cursorDev =14; {cursor moved event} 


{ Special cdevValue values } 


cdevGenErr = -1; {general error; gray cdev w/o alert} 

cdevMemErr = 0; {memory shortfall; alert user please} 

cdevResErr =135; {couldn't get a needed resource; alert} 

cdevUnset =..3% {cdevValue is initialized to this} 
Routines 


FUNCTION cdev(message, Item, numItems, CPaneLlID : INTEGER; 
VAR theEvent : EventRecord; cdevValue : LONGINT; 
CPDialog : DialogPtr) : LONGINT; 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE CONTROL PANEL ¢ 26 of 27 


Further Reference: 


Technical Note #215, "New" cdev Messages 
Technical Note #251, Safe cdevs 
32-Bit QuickDraw Documentation 


END OF DOCUMENT 
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